docs: add new migration guide to v12 documentation that describes how… #41828

aikithoughts · 2021-04-27T05:42:14Z

… to migrate older localization ids to new ones

PR Checklist

Please check if your PR fulfills the following requirements:

The commit message follows our guidelines: https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit
Tests for the changes have been added (for bug fixes / features)
Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

Bugfix
Feature
Code style update (formatting, local variables)
Refactoring (no functional changes, no api changes)
Build related changes
CI related changes
Documentation content changes
angular.io application / infrastructure changes
Other... Please describe:

What is the current behavior?

n/a

Issue Number: N/A

What is the new behavior?

New content that describes how to migrate legacy localization ids to new ones.

Does this PR introduce a breaking change?

Yes
No

Other information

mary-poppins · 2021-04-27T05:51:23Z

You can preview c59b3f1 at https://pr41828-c59b3f1.ngbuilds.io/.

petebacondarwin

Thanks for putting this together, @aikidave

petebacondarwin · 2021-04-27T05:47:02Z

aio/content/guide/migration-legacy-message-id.md

+
+   `npx localize-migrate --files=*.xlf --mapFile=messages.json`
+
+You now have a list of legacy localization IDs and new IDs, which you can use to update your application.


This line should actually be part of the previous step. I.e. after you have run localize-extract you now have a list of legacy IDs (the mapfile) that can be used to update the IDs in your translation files.

After running localize-migrate your translation files should now have been updated to use the new IDs. There should be nothing more to do on the application side.

aio/content/guide/migration-legacy-message-id.md

petebacondarwin · 2021-04-27T05:50:31Z

aio/content/guide/migration-legacy-message-id.md

+
+Angular version 12 introduces tooling to help you migrate any existing localization ids to ids that use the latest algorithms.
+
+You have two options for migrating legacy IDs. The first method locates existing IDs, creates new IDs, and replaces the old IDs. The second method is for cases custom localization processes, such as where your localization IDs are not stored in the Angular application. Use this second method if you store your IDs in a database. This method locates legacy IDs and then creates a set of new IDs that you can then use to replace the old ones.


The only difference (really) between the two solutions is that the first (and by far the most common) will be to use the CLI to locate existing IDs. The other solution is to use the standalone binary localize-extract to locate the existing IDs.

Both use the same second step, which is to run localize-migrate to update translation files.

petebacondarwin · 2021-04-27T05:53:42Z

aio/content/guide/migration-legacy-message-id.md

+
+## What this migration does
+
+Angular version 12 introduces tooling to help you migrate any existing localization ids to ids that use the latest algorithms.


Since v11, all new projects use the modern IDs by default.
Also any use of $localize in application code also uses the moden ID format.
Further, some projects use custom IDs (the set the ID for each translation manually themselves). That being said any legacy ICU messages will not have custom IDs and will need to be migrated.

So, strictly, this migration might not be necessary. Or at least when describing it we should be clear that we only need to migrate "legacy" IDs rather than all existing ones.

Thanks for this clarification, @petebacondarwin !

mary-poppins · 2021-04-27T16:01:20Z

You can preview dbb83c9 at https://pr41828-dbb83c9.ngbuilds.io/.

petebacondarwin

Looking good. A few more fixups needed.

petebacondarwin · 2021-04-27T15:56:51Z

aio/content/guide/migration-legacy-message-id.md

+
+Angular version 11 introduced a new format for localization IDs. These new IDs are more robust the previous, legacy format. However, applications created before version 11 still used the legacy format for these IDs.
+
+With the release of Angular version 12, you now how tools available to help you migrate any existing localization ids to ids that use the latest algorithms.


Suggested change

With the release of Angular version 12, you now how tools available to help you migrate any existing localization ids to ids that use the latest algorithms.

With the release of Angular version 12, you now have tools available to help you migrate any existing localization IDs to IDs that use the latest algorithms.

petebacondarwin · 2021-04-27T15:59:06Z

aio/content/guide/migration-legacy-message-id.md

+
+   `ng extract-i18n --format=legacy-migrate`
+
+   After running this command, you have a list of legacy localization IDs and new IDs, which you can use to update your application.


Suggested change

After running this command, you have a list of legacy localization IDs and new IDs, which you can use to update your application.

After running this command, you have a migration file (`messages.json`) containing a mapping between legacy localization IDs and new IDs, which you can use to update your application.

aio/content/guide/migration-legacy-message-id.md

petebacondarwin · 2021-04-27T16:00:42Z

aio/content/guide/migration-legacy-message-id.md

+
+## Migrate legacy IDs using `localize-extract`
+
+To migrate legacy localization IDs using `localize-extract`:


How about:

Suggested change

To migrate legacy localization IDs using `localize-extract`:

If you are not using the Angular CLI, then you can migrate legacy localization IDs using `localize-extract`:

petebacondarwin · 2021-04-27T16:01:26Z

aio/content/guide/migration-legacy-message-id.md

+
+   `npx localize-extract --format=legacy-migrate --source=./path/to/bundles --outputPath=./`
+
+   In this command, `./path/to/bundles/` represents the path to your localization files. You can set the `outputPath` parameter to any directory in your system.


Suggested change

In this command, `./path/to/bundles/` represents the path to your localization files. You can set the `outputPath` parameter to any directory in your system.

In this command, `./path/to/bundles/` represents the path to your distributable files. You can set the `outputPath` parameter to any directory in your system.

The bundles will be the generated JavaScript from whatever build tooling they are using.

petebacondarwin · 2021-04-27T16:14:04Z

aio/content/guide/migration-legacy-message-id.md

+
+   In this command, `./path/to/bundles/` represents the path to your localization files. You can set the `outputPath` parameter to any directory in your system.
+
+   After running this command, you have a list of legacy localization IDs and new IDs, which you can use to update your application.


Suggested change

After running this command, you have a list of legacy localization IDs and new IDs, which you can use to update your application.

After running this command, you have a migration file (`messages.json`) containing a mapping between legacy localization IDs and new IDs, which you can use to update your application.

aio/content/guide/migration-legacy-message-id.md

petebacondarwin · 2021-04-27T16:19:21Z

aio/content/guide/migration-legacy-message-id.md

+
+1. Run the `npx localize-extract` command.
+
+   `npx localize-extract --format=legacy-migrate --source=./path/to/bundles --outputPath=./`


The outputPath has to actually be a path to the file, not the directory. So

Suggested change

`npx localize-extract --format=legacy-migrate --source=./path/to/bundles --outputPath=./`

`npx localize-extract --format=legacy-migrate --source=./path/to/bundles --outputPath=./messages.json`

aio/content/guide/migration-legacy-message-id.md

ahasall · 2021-04-27T16:52:05Z

aio/content/guide/migration-legacy-message-id.md

+
+## What this migration does
+
+Angular version 11 introduced a new format for localization IDs. These new IDs are more robust the previous, legacy format. However, applications created before version 11 still used the legacy format for these IDs.


Suggested change

Angular version 11 introduced a new format for localization IDs. These new IDs are more robust the previous, legacy format. However, applications created before version 11 still used the legacy format for these IDs.

Angular version 11 introduced a new format for localization IDs. These new IDs are more robust than the previous, legacy format. However, applications created before version 11 still used the legacy format for these IDs.

Thank you, @ahasall !

aio/content/guide/migration-legacy-message-id.md

crisbeto · 2021-04-27T17:01:37Z

aio/content/guide/migration-legacy-message-id.md

+
+## Why is this migration necessary
+
+The Angular translation system works by matching a message ID to a translated message in a different language. One option for creating these IDs is to have the translation system generate them for you. Previous algorithms that created these IDs have, over time, become fragile to formatting changes. The new algorithms are much more robust. This migration system helps you improve application stability by creating new legacy IDs that you can add to your application.


In the last sentence, I'm not sure that "application stability" is the correct term. Migrating to the new system makes it more future-proof, because they won't have to migrate later when we remove the new format. It also means that the IDs will change less frequently.

aio/content/guide/migration-legacy-message-id.md

crisbeto · 2021-04-27T17:03:30Z

aio/content/navigation.json

+            {
+              "url": "guide/migration-legacy-message-id",
+              "title": "Migration: Legacy Localization IDs",
+              "tooltip": "Learn how to migrate older IDs for localization to new, more stable ones."


older -> old. I don't think that we have any older ID algorithms than the ones we're migrating away from.

TeriGlover · 2021-04-27T19:02:30Z

aio/content/guide/migration-legacy-message-id.md

+
+With the release of Angular version 12, you now how tools available to help you migrate any existing localization ids to ids that use the latest algorithms.
+
+You have two options for migrating legacy IDs. The first method uses the Angular CLI to locate legacy IDs in your application. The second method uses a standalone application, `localize-extract` to locate the legacy IDs.


Suggested change

You have two options for migrating legacy IDs. The first method uses the Angular CLI to locate legacy IDs in your application. The second method uses a standalone application, `localize-extract` to locate the legacy IDs.

You have two options for migrating legacy IDs. The first method uses the Angular CLI to locate legacy IDs in your application. The second method uses a standalone application, `localize-extract`, to locate the legacy IDs.

TeriGlover · 2021-04-27T19:06:51Z

aio/content/guide/migration-legacy-message-id.md

+
+## What this migration does
+
+Angular version 11 introduced a new format for localization IDs. These new IDs are more robust the previous, legacy format. However, applications created before version 11 still used the legacy format for these IDs.


Suggested change

Angular version 11 introduced a new format for localization IDs. These new IDs are more robust the previous, legacy format. However, applications created before version 11 still used the legacy format for these IDs.

Angular version 11 introduced a new format for localization IDs. These new IDs are more robust the previous legacy format. However, applications created before version 11 still used the legacy format for these IDs.

TeriGlover · 2021-04-27T19:17:03Z

aio/content/guide/migration-legacy-message-id.md

+   You can also specify other formats in the `files` parameter, such as `*.xmb`.
+   </div>
+
+## Why is this migration necessary


Suggested change

## Why is this migration necessary

## Why this migration is necessary

Moved word for better flow

TeriGlover · 2021-04-27T19:19:40Z

Editing review completed; a few minor suggestions.

…

On Tue, Apr 27, 2021 at 11:00 AM Pete Bacon Darwin ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In aio/content/guide/migration-legacy-message-id.md <#41828 (comment)>: > + +You have two options for migrating legacy IDs. The first method uses the Angular CLI to locate legacy IDs in your application. The second method uses a standalone application, `localize-extract` to locate the legacy IDs. + +## Migrating legacy IDs using the CLI + +To migrate legacy localization IDs using the CLI: + +1. Run the `ng extract-i18n` command. + + `ng extract-i18n --format=legacy-migrate` + + After running this command, you have a list of legacy localization IDs and new IDs, which you can use to update your application. + +1. Update the IDs in your application using the `npx localize-migrate` command. + + `npx localize-migrate --files=*.xlf --mapFile=messages.json` In that case, you can ignore my comments about npx and move on. — You are receiving this because your review was requested. Reply to this email directly, view it on GitHub <#41828 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AR4DPGRJY54O62MJ5ISU633TK33TBANCNFSM43UISTFQ> .

-- *--Teri Glover--* *Technical Editor*

jelbourn · 2021-04-27T22:14:20Z

aio/content/guide/migration-legacy-message-id.md

+
+## Why is this migration necessary
+
+The Angular translation system works by matching a message ID to a translated message in a different language. One option for creating these IDs is to have the translation system generate them for you. Previous algorithms that created these IDs have, over time, become fragile to formatting changes. The new algorithms are much more robust. This migration system helps you improve application stability by creating new legacy IDs that you can add to your application.


It seems like it would be useful to move the content from "why is this migration necessary" higher up so that people more quickly know why they should care about this migration in the first place.

I was following the pattern of previous migration guides, but I agree. I'll put this section ahead of "What this migration does"

aikithoughts

Thanks for the feedback!

aikithoughts · 2021-04-29T21:31:56Z

aio/content/guide/migration-legacy-message-id.md

+
+## What this migration does
+
+Angular version 11 introduced a new format for localization IDs. These new IDs are more robust the previous, legacy format. However, applications created before version 11 still used the legacy format for these IDs.


Thank you, @ahasall !

aio/content/guide/migration-legacy-message-id.md

aikithoughts · 2021-04-29T21:43:49Z

aio/content/guide/migration-legacy-message-id.md

+
+## Why is this migration necessary
+
+The Angular translation system works by matching a message ID to a translated message in a different language. One option for creating these IDs is to have the translation system generate them for you. Previous algorithms that created these IDs have, over time, become fragile to formatting changes. The new algorithms are much more robust. This migration system helps you improve application stability by creating new legacy IDs that you can add to your application.


I was following the pattern of previous migration guides, but I agree. I'll put this section ahead of "What this migration does"

mary-poppins · 2021-04-29T21:56:24Z

You can preview 2c95e78 at https://pr41828-2c95e78.ngbuilds.io/.

aio/content/guide/migration-legacy-message-id.md

crisbeto · 2021-04-30T10:28:22Z

aio/content/guide/migration-legacy-message-id.md

+
+1. Commit the updated files to your source control system.
+
+After you complete the migration, set the Angular Compiler option, `enableI18nLegacyMessageIdFormat`, to `false`. For more information about this option, see [Angular Compiler Options](/guide/angular-compiler-options#enablei18nlegacymessageidformat).


It seems like this paragraph is both here and at the bottom of the guide. Should one of them be removed?

No, because these are two different sections. Folks who are reading one may not read the other.

jelbourn

lgtm aside from other outstanding comments

mary-poppins · 2021-05-03T19:24:26Z

You can preview 97d4465 at https://pr41828-97d4465.ngbuilds.io/.

TeriGlover

One overlooked item in editing pass.

TeriGlover · 2021-05-03T19:47:33Z

aio/content/guide/migration-legacy-message-id.md

+
+</div>
+
+With the release of Angular version 12, you now have how tools available to help you migrate any existing localization IDs to IDs that use the latest algorithms.


Suggested change

With the release of Angular version 12, you now have how tools available to help you migrate any existing localization IDs to IDs that use the latest algorithms.

With the release of Angular version 12, you now have tools available to help you migrate any existing localization IDs to IDs that use the latest algorithms.

Deleted unnecessary word.

crisbeto

LGTM

petebacondarwin

This is looking great @aikidave - thanks for your patience with my confusion over the utility of npx.

aio/content/guide/migration-legacy-message-id.md

aio/content/navigation.json

petebacondarwin · 2021-05-03T20:10:18Z

Oh two more things...

Can we add a {@searchKeywords i18n} search keyword tag to help this appear when the user searches for i18n.
Can we try using <code-example> blocks for the command line instructions. In the previews, the code blocks are a bit unclear to me.

E.g.

<code-example language="bash">
ng extract-i18n --format=legacy-migrate
</code-example>

.pullapprove.yml

mary-poppins · 2021-05-03T20:46:21Z

You can preview ed46fe6 at https://pr41828-ed46fe6.ngbuilds.io/.

… to migrate older localization ids to new ones

mary-poppins · 2021-05-03T21:01:45Z

You can preview d9cde61 at https://pr41828-d9cde61.ngbuilds.io/.

… to migrate older localization ids to new ones (#41828) PR Close #41828

e-oz · 2021-05-06T11:54:19Z

Thank you, it was really usefull.

angular-automatic-lock-bot · 2021-06-06T16:15:45Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

aikithoughts requested review from crisbeto and TeriGlover April 27, 2021 05:42

google-cla bot added the cla: yes label Apr 27, 2021

pullapprove bot requested a review from jelbourn April 27, 2021 05:42

aikithoughts added comp: docs target: rc This PR is targeted for the next release-candidate labels Apr 27, 2021

ngbot bot modified the milestone: Backlog Apr 27, 2021

petebacondarwin requested changes Apr 27, 2021

View reviewed changes

aikithoughts force-pushed the legacy-id-migration branch from c59b3f1 to dbb83c9 Compare April 27, 2021 15:50

petebacondarwin requested changes Apr 27, 2021

View reviewed changes

ahasall reviewed Apr 27, 2021

View reviewed changes

crisbeto reviewed Apr 27, 2021

View reviewed changes

TeriGlover approved these changes Apr 27, 2021

View reviewed changes

jelbourn reviewed Apr 27, 2021

View reviewed changes

aikithoughts commented Apr 29, 2021

View reviewed changes

aikithoughts force-pushed the legacy-id-migration branch from dbb83c9 to 2c95e78 Compare April 29, 2021 21:46

crisbeto reviewed Apr 30, 2021

View reviewed changes

jelbourn approved these changes Apr 30, 2021

View reviewed changes

aikithoughts force-pushed the legacy-id-migration branch from 2c95e78 to 97d4465 Compare May 3, 2021 19:14

aikithoughts requested review from petebacondarwin and crisbeto May 3, 2021 19:15

aikithoughts mentioned this pull request May 3, 2021

docs: add redirect and update updating-to-v11 to v12 #41625

Closed

TeriGlover approved these changes May 3, 2021

View reviewed changes

crisbeto approved these changes May 3, 2021

View reviewed changes

petebacondarwin requested changes May 3, 2021

View reviewed changes

petebacondarwin reviewed May 3, 2021

View reviewed changes

.pullapprove.yml Outdated Show resolved Hide resolved

aikithoughts force-pushed the legacy-id-migration branch from 97d4465 to ed46fe6 Compare May 3, 2021 20:34

aikithoughts requested a review from petebacondarwin May 3, 2021 20:35

petebacondarwin approved these changes May 3, 2021

View reviewed changes

petebacondarwin reviewed May 3, 2021

View reviewed changes

.pullapprove.yml Outdated Show resolved Hide resolved

petebacondarwin added the aio: preview label May 3, 2021

docs: add new migration guide to v12 documentation that describes how…

d9cde61

… to migrate older localization ids to new ones

aikithoughts force-pushed the legacy-id-migration branch from ed46fe6 to d9cde61 Compare May 3, 2021 20:49

aikithoughts added the action: merge The PR is ready for merge by the caretaker label May 3, 2021

mhevery closed this in 6d7d659 May 4, 2021

mhevery pushed a commit that referenced this pull request May 4, 2021

docs: add new migration guide to v12 documentation that describes how…

2d9bfdf

… to migrate older localization ids to new ones (#41828) PR Close #41828

angular-automatic-lock-bot bot locked and limited conversation to collaborators Jun 6, 2021


		`npx localize-migrate --files=*.xlf --mapFile=messages.json`

		You now have a list of legacy localization IDs and new IDs, which you can use to update your application.


		Angular version 12 introduces tooling to help you migrate any existing localization ids to ids that use the latest algorithms.

		You have two options for migrating legacy IDs. The first method locates existing IDs, creates new IDs, and replaces the old IDs. The second method is for cases custom localization processes, such as where your localization IDs are not stored in the Angular application. Use this second method if you store your IDs in a database. This method locates legacy IDs and then creates a set of new IDs that you can then use to replace the old ones.


		## What this migration does

		Angular version 12 introduces tooling to help you migrate any existing localization ids to ids that use the latest algorithms.


		Angular version 11 introduced a new format for localization IDs. These new IDs are more robust the previous, legacy format. However, applications created before version 11 still used the legacy format for these IDs.

		With the release of Angular version 12, you now how tools available to help you migrate any existing localization ids to ids that use the latest algorithms.


		`ng extract-i18n --format=legacy-migrate`

		After running this command, you have a list of legacy localization IDs and new IDs, which you can use to update your application.

	After running this command, you have a list of legacy localization IDs and new IDs, which you can use to update your application.
	After running this command, you have a migration file (`messages.json`) containing a mapping between legacy localization IDs and new IDs, which you can use to update your application.


		## Migrate legacy IDs using `localize-extract`

		To migrate legacy localization IDs using `localize-extract`:

	To migrate legacy localization IDs using `localize-extract`:
	If you are not using the Angular CLI, then you can migrate legacy localization IDs using `localize-extract`:


		`npx localize-extract --format=legacy-migrate --source=./path/to/bundles --outputPath=./`

		In this command, `./path/to/bundles/` represents the path to your localization files. You can set the `outputPath` parameter to any directory in your system.


		1. Run the `npx localize-extract` command.

		`npx localize-extract --format=legacy-migrate --source=./path/to/bundles --outputPath=./`


		## Why is this migration necessary

		The Angular translation system works by matching a message ID to a translated message in a different language. One option for creating these IDs is to have the translation system generate them for you. Previous algorithms that created these IDs have, over time, become fragile to formatting changes. The new algorithms are much more robust. This migration system helps you improve application stability by creating new legacy IDs that you can add to your application.

	## Why is this migration necessary
	## Why this migration is necessary


		1. Commit the updated files to your source control system.

		After you complete the migration, set the Angular Compiler option, `enableI18nLegacyMessageIdFormat`, to `false`. For more information about this option, see [Angular Compiler Options](/guide/angular-compiler-options#enablei18nlegacymessageidformat).


		</div>

		With the release of Angular version 12, you now have how tools available to help you migrate any existing localization IDs to IDs that use the latest algorithms.

docs: add new migration guide to v12 documentation that describes how… #41828

docs: add new migration guide to v12 documentation that describes how… #41828

Conversation

aikithoughts commented Apr 27, 2021

PR Checklist

PR Type

What is the current behavior?

What is the new behavior?

Does this PR introduce a breaking change?

Other information

mary-poppins commented Apr 27, 2021

petebacondarwin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mary-poppins commented Apr 27, 2021

petebacondarwin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TeriGlover commented Apr 27, 2021 via email

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aikithoughts left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mary-poppins commented Apr 29, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jelbourn left a comment

Choose a reason for hiding this comment

mary-poppins commented May 3, 2021

TeriGlover left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

crisbeto left a comment

Choose a reason for hiding this comment

petebacondarwin left a comment

Choose a reason for hiding this comment

petebacondarwin commented May 3, 2021

mary-poppins commented May 3, 2021

mary-poppins commented May 3, 2021

e-oz commented May 6, 2021

angular-automatic-lock-bot bot commented Jun 6, 2021